unified-bridge

unified-bridge

Unified bridges transform the syntax tree from one processor to that of another processor. Then, they apply the destination processors plug-ins on said tree, before mutating the original origin tree based on the modified destination tree and continuing on running the origin plug-ins.

The exit step can be ignored.

         origin:run              destination:run               origin:run

        origin tree ---- \  / -- destination tree -- \  / ---- origin tree
          /               \/                          \/              \
         /                                                             \
        /             enter bridge                exit bridge           \
       /                                                                 \
     doc                                                                 doc

origin:parse                                                          origin:compile

Installation

npm:

npm install unified-bridge

unified-bridge is also available for duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

Usage

In remark-retext/index.js:

var bridge = require('unified-bridge');
var mdast2nlcst = require('mdast-util-to-nlcst');

function enter(origin, destination, file) {
    return mdast2nlcst(file, destination.Parser);
}

module.exports = bridge({
    'name': 'retext',
    'enter': enter
});

In example.js:

var remark = require('remark');
var retext = require('retext');
var report = require('vfile-reporter');
var lint = require('remark-lint');
var html = require('remark-html');
var equality = require('retext-equality');
var remark2retext = require('remark-retext');

remark()
    .use(lint)
    .use(remark2retext, retext().use(equality))
    .use(html)
    .process('## Hey guys\n', function (err, file, doc) {
        if (err) {
            throw err;
        } else {
            process.stderr.write(report(file) + '\n');
            process.stdout.write(doc);
        }
    });

Yields:

<stdin>
   1:1-1:12  warning  First heading level should be `1`                                    first-heading-level
   1:8-1:12  warning  `guys` may be insensitive, use `people`, `persons`, `folks` instead

⚠ 2 warnings
<h2>Hey guys</h2>

API

bridge(options)

Transform between two unified processors.

Parameters:

• options (Object):

  • name (string) — Name of destination syntax tree;

  • enter (Function) — Function invoked to transform the syntax tree of the origin processor into the syntax tree of the destination processor.

  • exit (Function?, optional) — Function invoked to transform the syntax tree after processing by the destination processor back into a syntax tree suitable for the origin processor.

Returns: Bridge — A bridge, which can be used as a plug-in for the origin parser you expect, accepting the expected destination processor as its options.

Throws: Error — When name or enter is not function.

function enter(origin, destination, file, node)

Transform node, which is a syntax tree produced by the origin processor, into a tree as if it was produced by the destination processor.

Parameters:

• origin (Processor) — Origin processor;

• destination (Processor) — Destination processor;

• file (VFile) — Processed file;

• node (Node) — Syntax tree for file suitable for origin.

Returns: Node — Syntax tree of the given document but mutated into a tree suitable for destination.

function exit(destination, origin, file, tree, node)

Transform node, which is a syntax tree produced by the origin processor, into a tree as if it was produced by the destination processor.

Parameters:

• origin (Processor) — Origin processor;

• destination (Processor) — Destination processor;

• file (VFile) — Processed file;

• tree (Node) — Syntax tree for file suitable for destination, previously produced by enter;

• node (Node) — Syntax tree for file suitable for origin, originally given to enter, which should be manipulated based on changes in tree.

License

MIT © Titus Wormer